<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <title>Additional features for translation - Zend Framework Manual</title>

    <link href="../css/shCore.css" rel="stylesheet" type="text/css" />
    <link href="../css/shThemeDefault.css" rel="stylesheet" type="text/css" />
    <link href="../css/styles.css" media="all" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Zend Framework</h1>
<h2>Programmer's Reference Guide</h2>
<ul>
    <li><a href="../en/zend.translate.additional.html">Inglês (English)</a></li>
    <li><a href="../pt-br/zend.translate.additional.html">Português Brasileiro (Brazilian Portuguese)</a></li>
</ul>
<table width="100%">
    <tr valign="top">
        <td width="85%">
            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.translate.sourcecreation.html">Creating source files</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.translate.html">Zend_Translate</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.translate.plurals.html">Plural notations for Translation</a></div>
                    </td>
                </tr>
            </table>
<hr />
<div id="zend.translate.additional" class="section"><div class="info"><h1 class="title">Additional features for translation</h1></div>
    

    <p class="para">
        There are several additional features which are supported by
        <span class="classname">Zend_Translate</span>. Read here for these additional informations.
    </p>

    <div class="section" id="zend.translate.additional.options"><div class="info"><h1 class="title">Options for adapters</h1></div>
        

        <p class="para">
            Options can be used with all adapters. Of course the options are different for all
            adapters. You can set options when you create the adapter. Actually there is one option
            which is available to all adapters: &#039;<em class="emphasis">clear</em>&#039; sets if translation
            data should be added to existing one or not. Standard behaviour is to add new
            translation data to existing one. But the translation data is only cleared for the
            selected language. So other languages remain untouched.
        </p>

        <p class="para">
            You can set options temporarily by giving them to
             <span class="methodname">addTranslation()</span>. And you can use the method
             <span class="methodname">setOptions()</span> to set options permanent.
        </p>

        <div class="example" id="zend.translate..additional.options.example"><div class="info"><p><b>Example #1 Using translation options</b></p></div>
            

            <pre class="programlisting brush: php">
// define &#039;:&#039; as separator for the translation source files
$translate = new Zend_Translate(
    array(
        &#039;adapter&#039; =&gt; &#039;csv&#039;,
        &#039;content&#039; =&gt; &#039;/path/to/mytranslation.csv&#039;,
        &#039;locale&#039;  =&gt; &#039;de&#039;,
        &#039;delimiter&#039; =&gt; &#039;:&#039;
    )
);

...

// clear the defined language and use new translation data
$translate-&gt;addTranslation(
    array(
        &#039;content&#039; =&gt; &#039;/path/to/new.csv&#039;,
        &#039;locale&#039;  =&gt; &#039;fr&#039;,
        &#039;clear&#039;   =&gt; true
    )
);
</pre>

        </div>

        <p class="para">
            Here you can find all available options for the different adapters with a description
            of their usage:
        </p>

        <table id="zend.translate.additional.options.alloptions" class="doctable table"><div class="info"><caption><b>Options for translation adapters</b></caption></div>
            

            
                <thead valign="middle">
                    <tr valign="middle">
                        <th>Option</th>
                        <th>Adapter</th>
                        <th>Description</th>
                        <th>Default value</th>
                    </tr>

                </thead>


                <tbody valign="middle" class="tbody">
                    <tr valign="middle">
                        <td align="left">adapter</td>
                        <td align="left"><span class="classname">Zend_Translate</span> only</td>

                        <td align="left">
                            Defines the adapter which will be used for the translation. This option
                            can only be given when a new instance of
                            <span class="classname">Zend_Translate</span> is created. When it is set
                            afterwards, then it will be ignored
                        </td>

                        <td align="left"><em class="emphasis">Must be set as it has no default value</em></td>
                    </tr>


                    <tr valign="middle">
                        <td align="left">clear</td>
                        <td align="left">all</td>

                        <td align="left">
                            If set to <b><tt>TRUE</tt></b>, the already read translations will
                            be cleared. This can be used instead of creating a new instance when
                            reading new translation data
                        </td>

                        <td align="left"><em class="emphasis"><b><tt>FALSE</tt></b></em></td>
                    </tr>


                    <tr valign="middle">
                        <td align="left">cache</td>
                        <td align="left">all</td>

                        <td align="left">
                            Sets a cache for the translation adapter. This must be a instance of
                            <span class="classname">Zend_Cache_Core</span>
                        </td>

                        <td align="left">
                            <em class="emphasis">Per default no cache is set</em>
                        </td>
                    </tr>


                    <tr valign="middle">
                        <td align="left">content</td>
                        <td align="left">all</td>

                        <td align="left">
                            Sets the content for the translation adapter. This could be an array,
                            a filename or a directory. Which type of content is supported depends
                            on the used adapter
                        </td>

                        <td align="left">
                            <em class="emphasis">The default value depends on the used adapter</em>
                        </td>
                    </tr>


                    <tr valign="middle">
                        <td align="left">disableNotices</td>
                        <td align="left">all</td>

                        <td align="left">
                            If set to <b><tt>TRUE</tt></b>, all notices regarding not available
                            translations will be disabled. You should set this option to
                            <b><tt>TRUE</tt></b> in production environment
                        </td>

                        <td align="left"><em class="emphasis"><b><tt>FALSE</tt></b></em></td>
                    </tr>


                    <tr valign="middle">
                        <td align="left">ignore</td>
                        <td align="left">all</td>

                        <td align="left">
                            All directories and files beginning with this prefix will be ignored
                            when searching for files. This value defaults to
                            <em class="emphasis">&#039;.&#039;</em> which leads to the behavior that all hidden
                            files will be ignored. Setting this value to <em class="emphasis">&#039;tmp&#039;</em>
                            would mean that directories and files like &#039;tmpImages&#039; and
                            &#039;tmpFiles&#039; would be ignored as well as all subsequent
                            directories. This option also accepts an array which can be used when
                            you want to ignore more than one prefix.
                        </td>

                        <td align="left"><em class="emphasis">.</em></td>
                    </tr>


                    <tr valign="middle">
                        <td align="left">log</td>
                        <td align="left">all</td>

                        <td align="left">
                            An instance of <span class="classname">Zend_Log</span> where untranslated
                            messages and notices will be written to
                        </td>

                        <td align="left"><em class="emphasis"><b><tt>NULL</tt></b></em></td>
                    </tr>


                    <tr valign="middle">
                        <td align="left">logMessage</td>
                        <td align="left">all</td>
                        <td align="left">The message which will be written into the log</td>

                        <td align="left">
                            <em class="emphasis">Untranslated message within &#039;%locale%&#039;: %message%</em>
                        </td>
                    </tr>


                    <tr valign="middle">
                        <td align="left">logPriority</td>
                        <td align="left">all</td>
                        <td align="left">The priority which is used to write the message into the log</td>

                        <td align="left">
                            <em class="emphasis">5</em>
                        </td>
                    </tr>


                    <tr valign="middle">
                        <td align="left">logUntranslated</td>
                        <td align="left">all</td>

                        <td align="left">
                            When this option is set to <b><tt>TRUE</tt></b>, all message IDs
                            which can not be translated will be written into the attached log
                        </td>

                        <td align="left"><em class="emphasis"><b><tt>FALSE</tt></b></em></td>
                    </tr>


                    <tr valign="middle">
                        <td align="left">reload</td>
                        <td align="left">all</td>

                        <td align="left">
                            When this option is set to <b><tt>TRUE</tt></b>, then files are
                            reloaded into the cache. This option can be used to recreate the cache,
                            or to add translations to already cached data after the cache has
                            already been created.
                        </td>

                        <td align="left"><em class="emphasis"><b><tt>FALSE</tt></b></em></td>
                    </tr>


                    <tr valign="middle">
                        <td align="left">route</td>
                        <td align="left">all</td>

                        <td align="left">
                            This option allows to use reroute from non existing translations to
                            other languages. See the <a href="zend.translate.additional.html#zend.translate.additional.rerouting" class="link">Rerouting
                                Section</a> for details about this option.
                        </td>

                        <td align="left"><em class="emphasis"><b><tt>NULL</tt></b></em></td>
                    </tr>


                    <tr valign="middle">
                        <td align="left">scan</td>
                        <td align="left">all</td>

                        <td align="left">
                            If set to <b><tt>NULL</tt></b>, no scanning of the directory
                            structure will be done. If set to
                            <b><tt>Zend_Translate::LOCALE_DIRECTORY</tt></b> the
                            locale will be detected within the directory. If set to
                            <b><tt>Zend_Translate::LOCALE_FILENAME</tt></b> the locale will
                            be detected within the filename. See <a href="zend.translate.additional.html#zend.translate.additional.detection" class="link">this chapter</a>
                            for details
                        </td>

                        <td align="left"><em class="emphasis"><b><tt>NULL</tt></b></em></td>
                    </tr>


                    <tr valign="middle">
                        <td align="left">tag</td>
                        <td align="left">all</td>

                        <td align="left">
                            Sets an individual tag which is used for the attached cache. Using this
                            option allows to use and clear the cache for single instances. When this
                            option is not set, the attached cache is used for all instances combined
                        </td>

                        <td align="left"><em class="emphasis"><span class="classname">Zend_Translate</span></em></td>
                    </tr>


                    <tr valign="middle">
                        <td align="left">delimiter</td>
                        <td align="left">Csv</td>

                        <td align="left">
                            Defines which sign is used as delimiter for separating source and
                            translation
                        </td>

                        <td align="left"><em class="emphasis">;</em></td>
                    </tr>


                    <tr valign="middle">
                        <td align="left">enclosure</td>
                        <td align="left">Csv</td>

                        <td align="left">
                            Defines the enclosure character to be used. Defaults to a doublequote
                        </td>

                        <td align="left"><em class="emphasis">&quot;</em></td>
                    </tr>


                    <tr valign="middle">
                        <td align="left">length</td>
                        <td align="left">Csv</td>

                        <td align="left">
                            Defines the maximum length of a csv line. When set to 0 it will be
                            detected automatically
                        </td>

                        <td align="left"><em class="emphasis">0</em></td>
                    </tr>


                    <tr valign="middle">
                        <td align="left">useId</td>
                        <td align="left">Xliff and Tmx</td>

                        <td align="left">
                            If you set this option to <b><tt>FALSE</tt></b>, then the source
                            string will be used as message Id. The default for this option is
                            <b><tt>TRUE</tt></b>, which means that the Id from the trans-unit
                            element will be used as message Id
                        </td>

                        <td align="left"><em class="emphasis"><b><tt>TRUE</tt></b></em></td>
                    </tr>

                </tbody>
            
        </table>


        <p class="para">
            When you want to have self defined options, you are also able to use them within all
            adapters. The  <span class="methodname">setOptions()</span> method can be used to define your
            option.  <span class="methodname">setOptions()</span> needs an array with the options you want
            to set. If an given option exists it will be signed over. You can define as much options
            as needed as they will not be checked by the adapter. Just make sure not to overwrite
            any existing option which is used by an adapter.
        </p>

        <p class="para">
            To return the option you can use the  <span class="methodname">getOptions()</span> method. When
             <span class="methodname">getOptions()</span> is called without a parameter it will return all
            options set. When the optional parameter is given you will only get the specified
            option.
        </p>
    </div>

    <div class="section" id="zend.translate.additional.languages"><div class="info"><h1 class="title">Handling languages</h1></div>
        

        <p class="para">
            When working with different languages there are a few methods which will be useful.
        </p>

        <p class="para">
            The  <span class="methodname">getLocale()</span> method can be used to get the currently set
            language. It can either hold an instance of <span class="classname">Zend_Locale</span> or the
            identifier of a locale.
        </p>

        <p class="para">
            The  <span class="methodname">setLocale()</span> method sets a new standard language for
            translation. This prevents the need of setting the optional language parameter more than
            once to the  <span class="methodname">translate()</span> method. If the given language does not
            exist, or no translation data is available for the language,
             <span class="methodname">setLocale()</span> tries to downgrade to the language without the
            region if any was given. A language of <em class="emphasis">en_US</em> would be downgraded to
            <em class="emphasis">en</em>. When even the downgraded language can not be found an exception
            will be thrown.
        </p>

        <p class="para">
            The  <span class="methodname">isAvailable()</span> method checks if a given language is already
            available. It returns <b><tt>TRUE</tt></b> if data for the given language exist.
        </p>

        <p class="para">
            And finally the  <span class="methodname">getList()</span> method can be used to get all
            currently set languages for an adapter returned as array.
        </p>

        <div class="example" id="zend.translate.additional.languages.example"><div class="info"><p><b>Example #2 Handling languages with adapters</b></p></div>
            

            <pre class="programlisting brush: php">
// returns the currently set language
$actual = $translate-&gt;getLocale();

// you can use the optional parameter while translating
echo $translate-&gt;_(&quot;my_text&quot;, &quot;fr&quot;);
// or set a new language
$translate-&gt;setLocale(&quot;fr&quot;);
echo $translate-&gt;_(&quot;my_text&quot;);
// refer to the base language
// fr_CH will be downgraded to fr
$translate-&gt;setLocale(&quot;fr_CH&quot;);
echo $translate-&gt;_(&quot;my_text&quot;);

// check if this language exist
if ($translate-&gt;isAvailable(&quot;fr&quot;)) {
    // language exists
}
</pre>

        </div>

        <div class="section" id="zend.translate.additional.languages.automatic"><div class="info"><h1 class="title">Automatical handling of languages</h1></div>
            

            <p class="para">
                Note that as long as you only add new translation sources with the
                 <span class="methodname">addTranslation()</span> method
                <span class="classname">Zend_Translate</span> will automatically set the best fitting
                language for your environment when you use one of the automatic locales which are
                &#039;<em class="emphasis">auto</em>&#039; or &#039;<em class="emphasis">browser</em>&#039;. So normally you will
                not need to call  <span class="methodname">setLocale()</span>. This should only be used in
                conjunction with automatic source detection.
            </p>

            <p class="para">
                The algorithm will search for the best fitting locale depending on the user&#039;s
                browser and your environment. See the following example for details:
            </p>

            <div class="example" id="zend.translate.additional.languages.automatic.example"><div class="info"><p><b>Example #3 Automatically language detection</b></p></div>
                

                <pre class="programlisting brush: php">
// Let&#039;s expect the browser returns these language settings:
// HTTP_ACCEPT_LANGUAGE = &quot;de_AT=1;fr=1;en_US=0.8&quot;;

// Example 1:
// When no fitting language is found, the message ID is returned
$translate = new Zend_Translate(
    array(
        &#039;adapter&#039; =&gt; &#039;gettext&#039;,
        &#039;content&#039; =&gt; &#039;my_it.mo&#039;,
        &#039;locale&#039;  =&gt; &#039;auto&#039;,
        &#039;scan&#039; =&gt; Zend_Translate::LOCALE_FILENAME
    )
);

// Example 2:
// Best found fitting language is &#039;fr&#039;
$translate = new Zend_Translate(
    array(
        &#039;adapter&#039; =&gt; &#039;gettext&#039;,
        &#039;content&#039; =&gt; &#039;my_fr.mo&#039;,
        &#039;locale&#039;  =&gt; &#039;auto&#039;,
        &#039;scan&#039; =&gt; Zend_Translate::LOCALE_FILENAME
    )
);

// Example 3:
// Best found fitting language is &#039;de&#039; (&#039;de_AT&#039; will be degraded)
$translate = new Zend_Translate(
    array(
        &#039;adapter&#039; =&gt; &#039;gettext&#039;,
        &#039;content&#039; =&gt; &#039;my_de.mo&#039;,
        &#039;locale&#039;  =&gt; &#039;auto&#039;,
        &#039;scan&#039; =&gt; Zend_Translate::LOCALE_FILENAME
    )
);

// Example 4:
// Returns &#039;it&#039; as translation source and overrides the automatic settings
$translate = new Zend_Translate(
    array(
        &#039;adapter&#039; =&gt; &#039;gettext&#039;,
        &#039;content&#039; =&gt; &#039;my_it.mo&#039;,
        &#039;locale&#039;  =&gt; &#039;auto&#039;,
        &#039;scan&#039; =&gt; Zend_Translate::LOCALE_FILENAME
    )
);

$translate-&gt;addTranslation(array(&#039;content&#039; =&gt; &#039;my_ru.mo&#039;, &#039;locale&#039; =&gt; &#039;ru&#039;));
$translate-&gt;setLocale(&#039;it_IT&#039;);
</pre>

            </div>

            <p class="para">
                After setting a language manually with the  <span class="methodname">setLocale()</span>
                method the automatic detection will be switched off and overridden.
            </p>

            <p class="para">
                If you want to use it again, you can set the language
                <em class="emphasis">auto</em> with  <span class="methodname">setLocale()</span> which will
                reactivate the automatic detection for <span class="classname">Zend_Translate</span>.
            </p>

            <p class="para">
                Since Zend Framework 1.7.0 <span class="classname">Zend_Translate</span> also recognises an
                application wide locale. You can simply set a <span class="classname">Zend_Locale</span>
                instance to the registry like shown below. With this notation you can forget about
                setting the locale manually with each instance when you want to use the same locale
                multiple times.
            </p>

            <pre class="programlisting brush: php">
// in your bootstrap file
$locale = new Zend_Locale();
Zend_Registry::set(&#039;Zend_Locale&#039;, $locale);

// default language when requested language is not available
$defaultlanguage = &#039;en&#039;;

// somewhere in your application
$translate = new Zend_Translate(
    array(&#039;adapter&#039; =&gt; &#039;gettext&#039;, &#039;content&#039; =&gt; &#039;my_de.mo&#039;)
);

if (!$translate-&gt;isAvailable($locale-&gt;getLanguage())) {
    // not available languages are rerouted to another language
    $translate-&gt;setLocale($defaultlanguage);
}

$translate-&gt;getLocale();
</pre>

        </div>

        <div class="section" id="zend.translate.additional.languages.territory"><div class="info"><h1 class="title">Using a country as language</h1></div>
            

            <p class="para">
                You can also use a country as locale parameter. This could be useful when you
                provide your user with flags, which represent the country in which he lives, and
                when he selects his flag, he would automatically get the default language for this
                country.
            </p>

            <p class="para">
                For example, when the user selected <em class="emphasis">US</em> then you would get
                <em class="emphasis">en_US</em> in return as locale which is being used. This leads
                automatically to the language <em class="emphasis">en</em> which is the default language
                for the country <em class="emphasis">US</em>.
            </p>

            <pre class="programlisting brush: php">
$translate = new Zend_Translate(
    array(
        &#039;adapter&#039; =&gt; &#039;gettext&#039;,
        &#039;content&#039; =&gt; &#039;my_de.mo&#039;,
        &#039;locale&#039;  =&gt; &#039;US&#039;
    )
);
</pre>


            <blockquote class="note"><p><b class="note">Note</b>: <span class="info"><b>Always uppercase countries</b><br /></span>
                

                <p class="para">
                    Using this syntax you should always uppercase the input when you know that it&#039;s
                    a country. The reason is that there are also languages which have the same
                    letters as a country. Take for example <em class="emphasis">om</em>. You could expect
                    to get <em class="emphasis">ar_OM</em> when you mean the country &quot;Oman&quot;, or you could
                    expect the language &quot;Oromo&quot; which is spoken in Kenia for example.
                </p>

                <p class="para">
                    As <span class="classname">Zend_Translate</span> is related to languages it will always
                    use the language in this case. Therefor always uppercase the locale when you
                    want it to be recognised as country.
                </p>
            </p></blockquote>
        </div>
    </div>

    <div class="section" id="zend.translate.additional.detection"><div class="info"><h1 class="title">Automatic source detection</h1></div>
        

        <p class="para">
            <span class="classname">Zend_Translate</span> can detect translation sources automatically. So
            you don&#039;t have to declare each source file manually. You can let
            <span class="classname">Zend_Translate</span> do this job and scan the complete directory
            structure for source files.
        </p>

        <blockquote class="note"><p><b class="note">Note</b>: 
            <p class="para">
                Automatic source detection is available since Zend Framework version 1.5 .
            </p>
        </p></blockquote>

        <p class="para">
            The usage is quite the same as initiating a single translation source with one
            difference. You must give a directory which has to be scanned instead a file.
        </p>

        <div class="example" id="zend.translate.additional.languages.directory.example"><div class="info"><p><b>Example #4 Scanning a directory structure for sources</b></p></div>
            

            <pre class="programlisting brush: php">
// assuming we have the following structure
//  /language/
//  /language/login/login.tmx
//  /language/logout/logout.tmx
//  /language/error/loginerror.tmx
//  /language/error/logouterror.tmx

$translate = new Zend_Translate(
    array(&#039;adapter&#039; =&gt; &#039;tmx&#039;, &#039;content&#039; =&gt; &#039;/language&#039;)
);
</pre>

        </div>

        <p class="para">
            So <span class="classname">Zend_Translate</span> does not only search the given directory, but
            also all subdirectories for translation source files. This makes the usage quite
            simple. But <span class="classname">Zend_Translate</span> will ignore all files which are not
            sources or which produce failures while reading the translation data. So you have to
            make sure that all of your translation sources are correct and readable because you
            will not get any failure if a file is bogus or can not be read.
        </p>

        <blockquote class="note"><p><b class="note">Note</b>: 
            <p class="para">
                Depending on how deep your directory structure is and how much files are within
                this structure it can take a long time for <span class="classname">Zend_Translate</span>
                to complete.
            </p>
        </p></blockquote>

        <p class="para">
            In our example we have used the <acronym class="acronym">TMX</acronym> format which includes the
            language to be used within the source. But many of the other source formats are not
            able to include the language within the file. Even this sources can be used with
            automatic scanning if you do some pre-requisits as described below:
        </p>

        <div class="section" id="zend.translate.additional.detection.directory"><div class="info"><h1 class="title">Language through naming directories</h1></div>
            

            <p class="para">
                One way to include automatic language detection is to name the directories related
                to the language which is used for the sources within this directory. This is the
                easiest way and is used for example within standard gettext implementations.
            </p>

            <p class="para">
                <span class="classname">Zend_Translate</span> needs the &#039;<span class="property">scan</span>&#039; option
                to know that it should search the names of all directories for languages. See the
                following example for details:
            </p>

            <div class="example" id="zend.translate.additional.detection.directory.example"><div class="info"><p><b>Example #5 Directory scanning for languages</b></p></div>
                

                <pre class="programlisting brush: php">
// assuming we have the following structure
//  /language/
//  /language/de/login/login.mo
//  /language/de/error/loginerror.mo
//  /language/en/login/login.mo
//  /language/en/error/loginerror.mo

$translate = new Zend_Translate(
    array(
        &#039;adapter&#039; =&gt; &#039;gettext&#039;,
        &#039;content&#039; =&gt; &#039;/language&#039;,
        &#039;scan&#039; =&gt; Zend_Translate::LOCALE_DIRECTORY
    )
);
</pre>

            </div>

            <blockquote class="note"><p><b class="note">Note</b>: 
                <p class="para">
                    This works only for adapters which do not include the language within the
                    source file. Using this option for example with <acronym class="acronym">TMX</acronym> will be
                    ignored. Also language definitions within the filename will be ignored when
                    using this option.
                </p>
            </p></blockquote>

            <blockquote class="note"><p><b class="note">Note</b>: 
                <p class="para">
                    You should be aware if you have several subdirectories under the same
                    structure. Assuming we have a structure like
                    <var class="filename">/language/module/de/en/file.mo</var>. In this case the path
                    contains multiple strings which would be detected as locale. It could be either
                    <em class="emphasis">de</em> or <em class="emphasis">en</em>. In such a case the behaviour
                    is undefined and it is recommended to use file detection in such situations.
                </p>
            </p></blockquote>
        </div>

        <div class="section" id="zend.translate.additional.detection.filename"><div class="info"><h1 class="title">Language through filenames</h1></div>
            

            <p class="para">
                Another way to detect the language automatically is to use special filenames. You
                can either name the complete file or parts of a file after the used language. To
                use this way of detection you will have to set the &#039;<span class="property">scan</span>&#039;
                option at initiation. There are several ways of naming the sourcefiles which are
                described below:
            </p>

            <div class="example" id="zend.translate.additional.detection.filename.example"><div class="info"><p><b>Example #6 Filename scanning for languages</b></p></div>
                

                <pre class="programlisting brush: php">
// assuming we have the following structure
//  /language/
//  /language/login/login_en.mo
//  /language/login/login_de.mo
//  /language/error/loginerror_en.mo
//  /language/error/loginerror_de.mo

$translate = new Zend_Translate(
    array(
        &#039;adapter&#039; =&gt; &#039;gettext&#039;,
        &#039;content&#039; =&gt; &#039;/language&#039;,
        &#039;scan&#039; =&gt; Zend_Translate::LOCALE_FILENAME
    )
);
</pre>

            </div>

            <div class="section" id="zend.translate.additional.detection.filename.complete"><div class="info"><h1 class="title">Complete filename</h1></div>
                

                <p class="para">
                    Having the whole file named after the language is the simplest way but only
                    viable if you have only one file per language.
                </p>

                <pre class="programlisting brush: txt">
/languages/
/languages/en.mo
/languages/de.mo
/languages/es.mo
</pre>

            </div>

            <div class="section" id="zend.translate.additional.detection.filename.extension"><div class="info"><h1 class="title">Extension of the file</h1></div>
                

                <p class="para">
                    Another simple way to use the extension of the file for language detection.
                    But this may be confusing since you will no longer have an idea which extension
                    the file originally had.
                </p>

                <pre class="programlisting brush: txt">
/languages/
/languages/view.en
/languages/view.de
/languages/view.es
</pre>

            </div>

            <div class="section" id="zend.translate.additional.detection.filename.token"><div class="info"><h1 class="title">Filename tokens</h1></div>
                

                <p class="para">
                    <span class="classname">Zend_Translate</span> is also capable of detecting the language
                    if it is included within the filename. But if you go this way you will have to
                    separate the language with a token. There are three supported tokens which can
                    be used: a dot &#039;.&#039;, an underscore &#039;_&#039;, or a hyphen &#039;-&#039;.
                </p>

                <pre class="programlisting brush: txt">
/languages/
/languages/view_en.mo -&gt; detects english
/languages/view_de.mo -&gt; detects german
/languages/view_it.mo -&gt; detects italian
</pre>


                <p class="para">
                    The first found string delimited by a token which can be interpreted as a
                    locale will be used. See the following example for details.
                </p>

                <pre class="programlisting brush: txt">
/languages/
/languages/view_en_de.mo -&gt; detects english
/languages/view_en_es.mo -&gt; detects english and overwrites the first file
/languages/view_it_it.mo -&gt; detects italian
</pre>


                <p class="para">
                    All three tokens are used to detect the locale. When the filename contains
                    multiple tokens, the first found token depends on the order of the tokens
                    which are used. See the following example for details.
                </p>

                <pre class="programlisting brush: txt">
/languages/
/languages/view_en-it.mo -&gt; detects english because &#039;_&#039; will be used before &#039;-&#039;
/languages/view-en_it.mo -&gt; detects italian because &#039;_&#039; will be used before &#039;-&#039;
/languages/view_en.it.mo -&gt; detects italian because &#039;.&#039; will be used before &#039;_&#039;
</pre>

            </div>
        </div>

        <div class="section" id="zend.translate.additional.detection.ignore"><div class="info"><h1 class="title">Ignoring special files and directories</h1></div>
            

            <p class="para">
                Sometimes it is useful to exclude files or even directories from being added
                automatically. Therefor you can use the <span class="property">ignore</span> option which
                accepts 3 possible usages.
            </p>

            <div class="section" id="zend.translate.additional.detection.ignore.string"><div class="info"><h1 class="title">Ignore a special directory or file</h1></div>
                

                <p class="para">
                    Per default <span class="classname">Zend_Translate</span> is set to ignore all
                    files and directories beginning with
                    <em class="emphasis">&#039;<var class="filename">/.</var>&#039;</em>. This means that
                    all <acronym class="acronym">SVN</acronym> files will be ignored.
                </p>

                <p class="para">
                    You can set your own syntax by giving a string for the
                    <span class="property">ignore</span> option. The directory separator will be attached
                    automatically and has to be omitted.
                </p>

                <pre class="programlisting brush: php">
$options   = array(&#039;ignore&#039; =&gt; &#039;test&#039;);
$translate = new Zend_Translate(
    array(
        &#039;adapter&#039; =&gt; $adapter,
        &#039;content&#039; =&gt; $content,
        &#039;locale&#039;  =&gt; $locale,
        &#039;ignore&#039;  =&gt; &#039;test&#039;
    )
);
</pre>


                <p class="para">
                    The above example will ignore all files and directories beginning with
                    <em class="emphasis">test</em>. This means for example
                    <var class="filename">/test/en.mo</var>, <var class="filename">/testing/en.mo</var> and
                    <var class="filename">/dir/test_en.mo</var>. But it would still add
                    <var class="filename">/mytest/en.mo</var> or <var class="filename">/dir/atest.mo</var>.
                </p>

                <blockquote class="note"><p><b class="note">Note</b>: <span class="info"><b>Prevent SVN files from being searched</b><br /></span>
                    

                    <p class="para">
                        When you set this option, then the default
                        <em class="emphasis">&#039;<var class="filename">/.</var>&#039;</em> will
                        be erased. This means that <span class="classname">Zend_Translate</span> will then
                        add all files from the hidden <acronym class="acronym">SVN</acronym> directories. When you
                        are working with <acronym class="acronym">SVN</acronym>, then you should use the array
                        syntax described in the next section.
                    </p>
                </p></blockquote>
            </div>

            <div class="section" id="zend.translate.additional.detection.ignore.array.files"><div class="info"><h1 class="title">Ignore several directories or files</h1></div>
                

                <p class="para">
                    You can also ignore several files and directories. Instead of a string,
                    you can simply give an array with all wished names which will be ignored.
                </p>

                <pre class="programlisting brush: php">
$options = array(&#039;ignore&#039; =&gt; array(&#039;.&#039;, &#039;test&#039;, &#039;old&#039;));
$translate = new Zend_Translate(
    array(
        &#039;adapter&#039; =&gt; $adapter,
        &#039;content&#039; =&gt; $content,
        &#039;locale&#039;  =&gt; $locale,
        &#039;ignore&#039;  =&gt; array(&#039;.&#039;, &#039;test&#039;, &#039;old&#039;)
    )
);
</pre>


                <p class="para">
                    In the above case all 3 syntax will be ignored. But still they have to
                    begin with the syntax to be detected and ignored.
                </p>
            </div>

            <div class="section" id="zend.translate.additional.detection.ignore.array.names"><div class="info"><h1 class="title">Ignore specific names</h1></div>
                

                <p class="para">
                    To ignore files and directories which are not beginning with a defined syntax
                    but have a special syntax anywhere within their name you can use a regular
                    expression.
                </p>

                <p class="para">
                    To use a regular expression the array key of the <span class="property">ignore</span>
                    option has to begin with <em class="emphasis">regex</em>.
                </p>

                <pre class="programlisting brush: php">
$options = array(
    &#039;ignore&#039; =&gt; array(
        &#039;regex&#039; =&gt; &#039;/test/u&#039;,
        &#039;regex_2&#039; =&gt; &#039;/deleted$/u&#039;
    )
);
$translate = new Zend_Translate(
    array(
        &#039;adapter&#039; =&gt; $adapter,
        &#039;content&#039; =&gt; $content,
        &#039;locale&#039;  =&gt; $locale,
        &#039;ignore&#039;  =&gt; array(&#039;regex&#039; =&gt; &#039;/test/u&#039;, &#039;regex_2&#039; =&gt; &#039;/deleted$/u&#039;)
    )
);
</pre>


                <p class="para">
                    In the above case we defined 2 regular expressions. The files and directories
                    will always being searched with all given regular expressions. In our example
                    this means that any files which contains <em class="emphasis">test</em> anywhere in
                    their name will be ignored. Additionally all files and directories which end
                    with <em class="emphasis">deleted</em> will not be added as translation.
                </p>
            </div>
        </div>
    </div>

    <div class="section" id="zend.translate.additional.rerouting"><div class="info"><h1 class="title">Routing for translations</h1></div>
        

        <p class="para">
            Not every message ID can be translated. But sometimes is can be useful to output the
            translation from another language instead of returning the message ID itself. You can
            archive this by using the <span class="property">route</span> option.
        </p>

        <p class="para">
            You can add one route for every language. See the following example:
        </p>

        <pre class="programlisting brush: php">
$translate = new Zend_Translate(
    array(
        &#039;adapter&#039; =&gt; $adapter,
        &#039;content&#039; =&gt; $content,
        &#039;locale&#039;  =&gt; $locale,
        &#039;route&#039;   =&gt; array(&#039;fr&#039; =&gt; &#039;en&#039;, &#039;de&#039; =&gt; &#039;fr&#039;)
    )
);
</pre>


        <p class="para">
            The above returns a english translation for all messages which can not be translated to
            french. And it returns a french translation for all messages which can not be translated
            to german. It will even return an english translation for all messages which can wether
            be translated to german nor to french. So you can even define a complete translation
            chain.
        </p>

        <p class="para">
            This feature seems ot be interesting for anyone. But be aware that returning
            translations for wrong or other languages can be problematic when the user does not
            understand this language. So you should always use this feature sparingly.
        </p>
    </div>

    <div class="section" id="zend.translate.additional.combination"><div class="info"><h1 class="title">Combining multiple translation sources</h1></div>
        

        <p class="para">
            When you are working with multiple translations you may come into a situation where you
            want to use different source types. For example the resource files which are provided
            by the framework and your own translations which are available by using the gettext
            adapter.
        </p>

        <p class="para">
            By combining multiple translation adapters you can use them within one instance. See
            the following example:
        </p>

        <pre class="programlisting brush: php">
$translate = new Zend_Translate(
    array(
        &#039;adapter&#039; =&gt; &#039;gettext&#039;,
        &#039;content&#039; =&gt; &#039;\path\to\translation.mo&#039;,
        &#039;locale&#039;  =&gt; &#039;en&#039;
    )
);

$translate_second = new Zend_Translate(
    array(
        &#039;adapter&#039; =&gt; &#039;array&#039;,
        &#039;content&#039; =&gt; &#039;\resources\languages\en\Zend_Validate.php&#039;,
        &#039;locale&#039;  =&gt; &#039;en&#039;
    )
);

$translate-&gt;addTranslation(array(&#039;content&#039; =&gt; $translate_second));
</pre>


        <p class="para">
            Now the first instance holds all translations from the second instance and you can use
            it within the application even if you used different source types.
        </p>

        <blockquote class="note"><p><b class="note">Note</b>: <span class="info"><b>Memory savings</b><br /></span>
            

            <p class="para">
                As you may have noted the second instance is no longer used as soon as it has been
                added to the first instance. To save some memory you may want to unset it.
            </p>
        </p></blockquote>

        <p class="para">
            When you are scanning for directories you may additionally want to use only one defined
            language. The predefined resources for example are available in more than 10 languages.
            But your application is not available in all of those language. Therefor you can also
            add only one language from the second adapter.
        </p>

        <pre class="programlisting brush: php">
$translate-&gt;addTranslation(
    array(
        &#039;content&#039; =&gt; $translate_second,
        &#039;locale&#039;  =&gt; &#039;en&#039;
    )
);
</pre>


        <p class="para">
            This allows you still to scan through the directories and still add only those languages
            which are relevant for your application.
        </p>
    </div>

    <div class="section" id="zend.translate.additional.istranslated"><div class="info"><h1 class="title">Checking for translations</h1></div>
        

        <p class="para">
            Normally text will be translated without any computation. But sometimes it is necessary
            to know if a text is translated or not, therefor the
             <span class="methodname">isTranslated()</span> method can be used.
        </p>

        <p class="para">
             <span class="methodname">isTranslated($messageId, $original = false, $locale = null)</span>
            takes the text you want to check as its first parameter, and as optional third parameter
            the locale for which you want to do the check. The optional second parameter declares
            whether translation is fixed to the declared language or a lower set of translations
            can be used. If you have a text which can be returned for &#039;en&#039; but not for &#039;en_US&#039; you
            will normally get the translation returned, but by setting <var class="varname">$original</var>
            to <b><tt>TRUE</tt></b>,  <span class="methodname">isTranslated()</span> will return
            <b><tt>FALSE</tt></b>.
        </p>

        <div class="example" id="zend.translate.additional.istranslated.example"><div class="info"><p><b>Example #7 Checking if a text is translatable</b></p></div>
            

            <pre class="programlisting brush: php">
$english = array(
    &#039;message1&#039; =&gt; &#039;Nachricht 1&#039;,
    &#039;message2&#039; =&gt; &#039;Nachricht 2&#039;,
    &#039;message3&#039; =&gt; &#039;Nachricht 3&#039;);

$translate = new Zend_Translate(
    array(
        &#039;adapter&#039; =&gt; &#039;array&#039;,
        &#039;content&#039; =&gt; $english,
        &#039;locale&#039; =&gt; &#039;de_AT&#039;
    )
);

if ($translate-&gt;isTranslated(&#039;message1&#039;)) {
    print &quot;&#039;message1&#039; can be translated&quot;;
}

if (!($translate-&gt;isTranslated(&#039;message1&#039;, true, &#039;de&#039;))) {
    print &quot;&#039;message1&#039; can not be translated to &#039;de&#039;&quot;
        . &quot; as it&#039;s available only in &#039;de_AT&#039;&quot;;
}

if ($translate-&gt;isTranslated(&#039;message1&#039;, false, &#039;de&#039;)) {
    print &quot;&#039;message1&#039; can be translated in &#039;de_AT&#039; as it falls back to &#039;de&#039;&quot;;
}
</pre>

        </div>
    </div>

    <div class="section" id="zend.translate.additional.logging"><div class="info"><h1 class="title">How to log not found translations</h1></div>
        

        <p class="para">
            When you have a bigger site or you are creating the translation files manually, you
            often have the problem that some messages are not translated. But there is an easy
            solution for you when you are using <span class="classname">Zend_Translate</span>.
        </p>

        <p class="para">
            You have to follow two or three simple steps. First, you have to create an instance of
            <span class="classname">Zend_Log</span>. Then you have to attach this instance to
            <span class="classname">Zend_Translate</span>. See the following example:
        </p>

        <div class="example" id="zend.translate.additional.logging.example"><div class="info"><p><b>Example #8 Log translations</b></p></div>
            

            <pre class="programlisting brush: php">
$translate = new Zend_Translate(
    array(
        &#039;adapter&#039; =&gt; &#039;gettext&#039;,
        &#039;content&#039; =&gt; $path,
        &#039;locale&#039; =&gt; &#039;de&#039;
    )
);

// Create a log instance
$writer = new Zend_Log_Writer_Stream(&#039;/path/to/file.log&#039;);
$log    = new Zend_Log($writer);

// Attach it to the translation instance
$translate-&gt;setOptions(
    array(
        &#039;log&#039;             =&gt; $log,
        &#039;logUntranslated&#039; =&gt; true
    )
);

$translate-&gt;translate(&#039;unknown string&#039;);
</pre>

        </div>

        <p class="para">
            Now you will have a new notice in the log:
            <em class="emphasis">Untranslated message within &#039;de&#039;: unknown string</em>.
        </p>

        <blockquote class="note"><p><b class="note">Note</b>: 
            <p class="para">
                You should note that any translation which can not be found will be logged. This
                means all translations when a user requests a language which is not supported. Also
                every request for a message which can not be translated will be logged. Be aware,
                that 100 people requesting the same translation, will result 100 logged notices.
            </p>
        </p></blockquote>

        <p class="para">
            This feature can not only be used to log messages but also to attach this untranslated
            messages into an empty translation file. To do so you will have to write your own log
            writer which writes the format you want to have and strips the prepending &quot;Untranslated
            message&quot;.
        </p>

        <p class="para">
            You can also set the &#039;<span class="property">logMessage</span>&#039; option when you want to have your
            own log message. Use the &#039;<em class="emphasis">%message%</em>&#039; token for placing the
            messageId within your log message, and the &#039;<em class="emphasis">%locale%</em>&#039; token for the
            requested locale. See the following example for a self defined log message:
        </p>

        <div class="example" id="zend.translate.additional.logging.example2"><div class="info"><p><b>Example #9 Self defined log messages</b></p></div>
            

            <pre class="programlisting brush: php">
$translate = new Zend_Translate(
    array(
        &#039;adapter&#039; =&gt; &#039;gettext&#039;,
        &#039;content&#039; =&gt; $path,
        &#039;locale&#039;  =&gt; &#039;de&#039;
    )
);

// Create a log instance
$writer = new Zend_Log_Writer_Stream(&#039;/path/to/file.log&#039;);
$log    = new Zend_Log($writer);

// Attach it to the translation instance
$translate-&gt;setOptions(
    array(
        &#039;log&#039;             =&gt; $log,
        &#039;logMessage&#039;      =&gt; &quot;Missing &#039;%message%&#039; within locale &#039;%locale%&#039;&quot;,
        &#039;logUntranslated&#039; =&gt; true
    )
);

$translate-&gt;translate(&#039;unknown string&#039;);
</pre>

        </div>

        <p class="para">
            Additionally you are also able to change the priority which is used to write the message
            into the log. Per default the priority <em class="emphasis">Zend_Log::NOTICE</em> is used.
            It equals with <em class="emphasis">5</em>. When you want to change the priority you can use
            any of <span class="classname">Zend_Log</span>&#039;s priorities. See the following example:
        </p>

        <div class="example" id="zend.translate.additional.logging.example3"><div class="info"><p><b>Example #10 Self defined log priority</b></p></div>
            

            <pre class="programlisting brush: php">
// Create a log instance
$writer = new Zend_Log_Writer_Stream(&#039;/path/to/file.log&#039;);
$log    = new Zend_Log($writer);

$translate = new Zend_Translate(
    array(
        &#039;adapter&#039; =&gt; &#039;gettext&#039;,
        &#039;content&#039; =&gt; $path,
        &#039;locale&#039;  =&gt; &#039;de&#039;,
        &#039;log&#039;             =&gt; $log,
        &#039;logMessage&#039;      =&gt; &quot;Missing &#039;%message%&#039; within locale &#039;%locale%&#039;&quot;,
        &#039;logPriority&#039;     =&gt; Zend_Log::ALERT,
        &#039;logUntranslated&#039; =&gt; true
    )
);

$translate-&gt;translate(&#039;unknown string&#039;);
</pre>

        </div>
    </div>

    <div class="section" id="zend.translate.additional.sourcedata"><div class="info"><h1 class="title">Accessing source data</h1></div>
        

        <p class="para">
            Sometimes it is useful to have access to the translation source data. Therefor
            the following two functions are provided.
        </p>

        <p class="para">
            The  <span class="methodname">getMessageIds($locale = null)</span> method returns all known
            message IDs as array.
        </p>

        <p class="para">
            When you want to know the message ID for a given translation then you can use the
             <span class="methodname">getMessageId()</span> method.
        </p>

        <p class="para">
            The  <span class="methodname">getMessages($locale = null)</span> method returns the complete
            translation source as an array. The message ID is used as key and the translation data
            as value.
        </p>

        <p class="para">
            Both methods accept an optional parameter <var class="varname">$locale</var> which, if set,
            returns the translation data for the specified language. If this parameter is not given,
            the actual set language will be used. Keep in mind that normally all translations should
            be available in all languages. Which means that in a normal situation you will not have
            to set this parameter.
        </p>

        <p class="para">
            Additionally the  <span class="methodname">getMessages()</span> method can be used to return the
            complete translation dictionary using the pseudo-locale &#039;all&#039;. This will return all
            available translation data for each added locale.
        </p>

        <blockquote class="note"><p><b class="note">Note</b>: 
            <p class="para">
                Attention: the returned array can be <em class="emphasis">very big</em>,
                depending on the number of added locales and the amount of translation data.
            </p>
        </p></blockquote>

        <div class="example" id="zend.translate.additional.sourcedata.example"><div class="info"><p><b>Example #11 Handling languages with adapters</b></p></div>
            

            <pre class="programlisting brush: php">
// returns all known message IDs
$messageIds = $translate-&gt;getMessageIds();
print_r($messageIds);

// or just for the specified language
$messageIds = $translate-&gt;getMessageIds(&#039;en_US&#039;);
print_r($messageIds);

// returns all the complete translation data
$source = $translate-&gt;getMessages();
print_r($source);
</pre>

        </div>
    </div>
</div>
        <hr />

            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.translate.sourcecreation.html">Creating source files</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.translate.html">Zend_Translate</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.translate.plurals.html">Plural notations for Translation</a></div>
                    </td>
                </tr>
            </table>
</td>
        <td style="font-size: smaller;" width="15%"> <style type="text/css">
#leftbar {
	float: left;
	width: 186px;
	padding: 5px;
	font-size: smaller;
}
ul.toc {
	margin: 0px 5px 5px 5px;
	padding: 0px;
}
ul.toc li {
	font-size: 85%;
	margin: 1px 0 1px 1px;
	padding: 1px 0 1px 11px;
	list-style-type: none;
	background-repeat: no-repeat;
	background-position: center left;
}
ul.toc li.header {
	font-size: 115%;
	padding: 5px 0px 5px 11px;
	border-bottom: 1px solid #cccccc;
	margin-bottom: 5px;
}
ul.toc li.active {
	font-weight: bold;
}
ul.toc li a {
	text-decoration: none;
}
ul.toc li a:hover {
	text-decoration: underline;
}
</style>
 <ul class="toc">
  <li class="header home"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="reference.html">Zend Framework Reference</a></li>
  <li class="header up"><a href="zend.translate.html">Zend_Translate</a></li>
  <li><a href="zend.translate.introduction.html">Introduction</a></li>
  <li><a href="zend.translate.adapter.html">Adapters for Zend_Translate</a></li>
  <li><a href="zend.translate.using.html">Using Translation Adapters</a></li>
  <li><a href="zend.translate.sourcecreation.html">Creating source files</a></li>
  <li class="active"><a href="zend.translate.additional.html">Additional features for translation</a></li>
  <li><a href="zend.translate.plurals.html">Plural notations for Translation</a></li>
 </ul>
 </td>
    </tr>
</table>

<script type="text/javascript" src="../js/shCore.js"></script>
<script type="text/javascript" src="../js/shAutoloader.js"></script>
<script type="text/javascript" src="../js/main.js"></script>

</body>
</html>